home *** CD-ROM | disk | FTP | other *** search
/ Freelog 22 / freelog 22.iso / Prog / Djgpp / DJDEV203.ZIP / info / utils.info < prev   
Encoding:
GNU Info File  |  2000-01-05  |  17.5 KB  |  499 lines
  1. This is Info file ../../info/utils.info, produced by Makeinfo version
  2. 1.68 from the input file utils.tex.
  3.  
  4. This is the reference manual for DJGPP V2's miscellaneous utilities
  5.  
  6. Copyright (c) 1995 DJ Delorie
  7.  
  8. 
  9. File: utils.info,  Node: Top,  Up: (dir)
  10.  
  11. This is the reference manual for the miscellaneous utility programs that
  12. come with DJGPP.
  13.  
  14. * Menu:
  15.  
  16.  
  17. * bin2h::       Convert binary data files to C include files.
  18.  
  19. * djecho::      Echo long command lines to files.
  20.  
  21. * djtar::       Extract or list files from (possibly compressed)
  22.         tar archives, with DOS filename conversion.
  23.  
  24. * dtou::        Convert text files from dos to unix.
  25. * utod::        Convert text files from unix to dos.
  26.  
  27. * gxx::         Build and link C++ programs
  28.  
  29. * redir::       Manage I/O Redirection.
  30.  
  31. * djsplit::     split large files into multiple files.
  32. * djmerge::     Merge multiple files into one file.
  33.  
  34. * texi2ps::     Convert texinfo files to Postscript.
  35.  
  36. * update::      conditionally copy one file to another.
  37.  
  38. 
  39. File: utils.info,  Node: bin2h,  Next: djecho,  Up: Top
  40.  
  41. bin2h
  42. *****
  43.  
  44. `bin2h' allows a developer to embed a binary file into a source file,
  45. by converting the binary data to an array of integer values.
  46.  
  47. Usage: `bin2h' `datafile' SYMBOL `headerfile'
  48.  
  49. The resulting header file has a format like this:
  50.  
  51.      unsigned char symbol[] = {
  52.        ... data ...
  53.      };
  54.  
  55. 
  56. File: utils.info,  Node: djecho,  Next: djtar,  Prev: bin2h,  Up: Top
  57.  
  58. djecho
  59. ******
  60.  
  61. This program simply echos whatever is given to it on the command line.
  62.  
  63. Usage: `djecho' [`-n'] [`-o' FILE] stuff . . .
  64.  
  65. `-n'
  66.      Do not emit the trailing newline after printing the text.
  67.  
  68. `-o FILE'
  69.      Send output to a FILE.
  70.  
  71. The purpose of this program is to be able to interact directly with
  72. `make''s ability to pass long command lines to programs.  If you use
  73. redirection, you aren't always able to handle long command lines
  74. (especially since echo is normally in `command.com').  With `djecho',
  75. you can, and you can use the `-o' option to redirect output to a file
  76. (and use the file later as a response file) without using dos's
  77. redirection.
  78.  
  79. 
  80. File: utils.info,  Node: djtar,  Next: dtou,  Prev: djecho,  Up: Top
  81.  
  82. djtar
  83. *****
  84.  
  85. Usage: `djtar' [`-n' `changeFile'] [`-o' `dir'] [`-t'|`-x'] [`-i']
  86. [`-v'] [`-p'] [`-.'|`-!.'] [`-d'|`-u'|`-b'] `tarfile'
  87.  
  88. `djtar' is a program that is designed to ease the problems related to
  89. extracting Unix tar files on a DOS machine.  The long file names and
  90. illegal characters make regular tar programs useless.  What `djtar'
  91. does is make some obvious name conversions automatically and give you an
  92. opportunity to provide alternate names for more difficult cases, where
  93. several filenames map to the same name in the restricted 8+3 DOS
  94. filename space.
  95.  
  96. `djtar' can read compressed tar files and decompress them on the fly.
  97. (This can be also achieved by piping the output of `gzip' to `djtar',
  98. but for very large archives you can run out of free disk space, because
  99. DOS implements pipes as temporary disk files.)  `djtar' knows about all
  100. the compression methods supported by `gzip', namely, deflation (by
  101. `gzip'), LZW compression (by `compress'), LZH compression (as with
  102. `compress -H' available with some versions of `compress'), or Huffman
  103. compression (by `pack').
  104.  
  105. `djtar' can also decompress files compressed with `zip' or `pkzip', but
  106. only if the `.zip' file contains only files compressed with either the
  107. `deflation' or `stored' (i.e., uncompressed, like with `pkzip -e0')
  108. methods.
  109.  
  110. `djtar' can also read tar archives (compressed or otherwise) written on
  111. a Unix machine to a diskette as a raw device (i.e., without DOS
  112. filesystem).  To use `djtar' with such archives, specify a name of the
  113. drive (like `A:') as a tarfile argument.
  114.  
  115. When extracting files from compressed archives, `djtar' will validate
  116. them with whatever reduntant checks are available with the compression
  117. format, and print diagnostic messages whenever these checks fail.  The
  118. checks and the diagnostics are generally identical to those performed
  119. by `gzip'.  Some of the diagnostics are only printed under the verbose
  120. operation switched on by the `-v' switch.  Unless you use the `-i'
  121. switch, `djtar' will refuse to create files and directories beyond the
  122. first tar directory entry which fails the checksum test; this usually
  123. means the file is either corrupted or not in a valid tar format.
  124.  
  125. An additional bonus of using `djtar' is that it can convert Unix-style
  126. text files to DOS-style text files, and vice versa.  By default, it
  127. will write all files exactly as found in the archive, but the `-u' and
  128. `-d' options can change that.
  129.  
  130. `djtar' performs a number of file name conversions in an attempt to
  131. make the files fit into MS-DOS's restricted file names.  Any file
  132. ending in `.info-N', where N is a number, becomes `.iN'.  Any file
  133. ending in `.tar.gz' becomes `.tgz'.  Any `++' string within a file name
  134. becomes `xx'.  Any leading dots are changed to underscores (but current
  135. and parent directories, `./' and `../' are left alone).  Any remaining
  136. multiple dots are changed to dashes, unless the part before the dot is
  137. shorter than 3 characters and there are more than 1 dot in the filename,
  138. in which case the dot also becomes an underscore.  As a result, e.g.,
  139. `.foo.a.b' becomes `_foo.a-b', and `sh.lex.c' becomes `sh_lex.c'.
  140.  
  141. While `djtar' is running, if it cannot successfully perform an
  142. exclusive open of the given file (it will refuse to overwrite an
  143. existing file), it will prompt you for a new name.  You may type in
  144. either a complete path, a replacement file name (no directory part), or
  145. just hit return (the file is skipped).
  146.  
  147. If `djtar' is called as `djtart', it behaves as if it were called with
  148. the `-t' switch; when called as `djtarx', it behaves like `djtar -x'.
  149. Thus you can create 2 links to `djtar.exe' which will save you some
  150. typing.
  151.  
  152. By default, `djtar' just lists the contents of the archive(s) given as
  153. its arguments.  If you want to extract files, you must use the `-x'
  154. option.
  155.  
  156. *Options:*
  157.  
  158. `-x'
  159.      By default, `djtar' just lists the contents of the archive(s)
  160.      given as its arguments.  If you want to extract files, you must use
  161.      this option, or call `djtar' via a link named `djtarx'.
  162.  
  163. `-t'
  164.      This option causes `djtar' to only print the contents of the tar
  165.      file, without actually creating any files.  All the decompression,
  166.      CRC checks etc. are still performed; thus, this option can also be
  167.      used to test archive integrity.  This is the default behavior of
  168.      `djtar', unless you call it via a link named `djtarx'.
  169.  
  170. `-v'
  171.      This option modifies the output format slightly to aid in
  172.      debugging tar file problems.  It also causes `djtar' to emit more
  173.      verbose warning messages and print the compression method for
  174.      compressed archives.
  175.  
  176. `-.'
  177.      Enable the automatic conversion of dots to underscores and dashes.
  178.      This is the default.
  179.  
  180. `-!.'
  181.      Disable the conversion of dots.  You get the control of file
  182.      renaming when names of several files clash.
  183.  
  184. `-n `changeFile''
  185.      This option allows you to specify a list of filename conversions
  186.      ahead of time.  Thus, you can use `djtart' or `djtar -t' to list
  187.      the files, figure out the new names with your favorite editor, and
  188.      supply that file to `djtar'.  This way, you have the fullest
  189.      possible control on how the extracted files will be named on your
  190.      system.
  191.  
  192.      The format of the `changeFile' file is like this:
  193.  
  194.           dir/dir/dir/old.name.here  dir/dir/dir/newname.hre
  195.           dir/dir/dir/old2.name.here  dir/dir/dir/newname2.hre
  196.  
  197.      The directories must be complete, not relative.  The "old"
  198.      directories must match the complete path in the tar file, and the
  199.      "new" directories indicate where the file goes on the DOS disk.
  200.  
  201. `-d'
  202.      Convert all text files to DOS text format on output.  This won't
  203.      usually affect binary files, but as `djtar' detects the file type
  204.      by looking at its first 512 bytes, a small possibility of a binary
  205.      file rendered useless by this conversion still exists, so you're
  206.      advised to only use this option with archives of text files.
  207.  
  208.      By default, `djtar' writes all files exactly as it finds them.
  209.  
  210. `-u'
  211.      Convert all text files to UNIX text format on output.  This won't
  212.      usually affect binary files, but as `djtar' detects the file type
  213.      by looking at its first 512 bytes, a small possibility of a binary
  214.      file rendered useless by this conversion still exists, so you're
  215.      advised to only use this option with archives of text files.
  216.  
  217.      By default, `djtar' writes all files exactly as it finds them.
  218.  
  219. `-b'
  220.      Write all files exactly as found in the archive, with no
  221.      conversions of text files.  This is the default.  Files written to
  222.      the console (when `-p' is in effect) are always written in text
  223.      mode, so this option doesn't have any effect when used with `-p',
  224.      unless the output of `djtar' is redirected to a file or a pipe.
  225.  
  226. `-o STRING'
  227.      Only extract files whose full path names begin with STRING.  This
  228.      option can be used to extract portions of archive.  Files which
  229.      aren't extracted will still be shown, but with a string `[ skipped
  230.      ]' appended to their names.  When given the `-o' option, `djtar'
  231.      actually checks if STRING is the initial substring of each
  232.      filename, so you can specify incomplete file names, thus using
  233.      `-o' as a poor man's wildcard facility.
  234.  
  235. `-i'
  236.      Attempt to unpack damaged archives.  By default, `djtar' will
  237.      refuse to create files whose directory entries in the tar archive
  238.      fail the checksum test, and any files beyond that point.  This
  239.      option tells `djtar' to ignore the checksum test and proceed
  240.      anyway.  Checksum failure usually means that the tar file is
  241.      either corrupted or not in valid tar format, so this option is
  242.      meant to be used either with the `-t' option, or in the rare cases
  243.      when you *know* for sure the tar file is valid (like if you had to
  244.      edit it to change the filenames).
  245.  
  246. `-p'
  247.      When given this switch, `djtar' will write the files to its
  248.      standard output, which can be piped into another program (like a
  249.      pager) or redirected to a file.  This option is designed to allow
  250.      you to view or extract individual files (e.g., the `README' files)
  251.      without having to open the entire archive, and should be used with
  252.      an appropriate `-o filename' option.
  253.  
  254.      When this option is used, diagnostic messages will be directed to
  255.      the standard error stream (as opposed to standard output in normal
  256.      operation), so that they won't get mixed with the files' data.
  257.  
  258. 
  259. File: utils.info,  Node: dtou,  Next: utod,  Prev: djtar,  Up: Top
  260.  
  261. dtou
  262. ****
  263.  
  264. Each file specified on the command line is converted from dos's CR/LF
  265. text file mode to unix's NL text file mode.
  266.  
  267. All djgpp wildcards are supported.  Timestamps of the files are
  268. preserved.
  269.  
  270. 
  271. File: utils.info,  Node: utod,  Next: gxx,  Prev: dtou,  Up: Top
  272.  
  273. utod
  274. ****
  275.  
  276. Each file specified on the command line is converted from unix's NL text
  277. file mode to dos's CR/LF text file mode.
  278.  
  279. All djgpp wildcards are supported.  Timestamps of the files are
  280. preserved.
  281.  
  282. 
  283. File: utils.info,  Node: gxx,  Next: redir,  Prev: utod,  Up: Top
  284.  
  285. gxx
  286. ***
  287.  
  288. This program is exactly like `gcc' (in fact, it calls gcc), except that
  289. it provides the extra libraries required to link most C++ programs,
  290. including the iostreams, stdc, and libg++ libraries.
  291.  
  292. 
  293. File: utils.info,  Node: redir,  Next: djsplit,  Prev: gxx,  Up: Top
  294.  
  295. redir
  296. *****
  297.  
  298. DOS, in its many flavors and versions, lacks a decent I/O redirection
  299. mechanism.  Sure, it's got < and > and >>, but what about error
  300. messages?  Lots of people ask, "How do you send those error messages to
  301. a file?"  Well, you use a program like `redir'.
  302.  
  303. `redir' is basically a program that manipulates the standard file
  304. descriptors by copying them, closing and opening them, etc.  Once it
  305. has the file descriptors where it wants them, it runs your program,
  306. which inherits the changed descriptors.  Thus, `redir' has nearly
  307. complete control over the input and output of your program.
  308.  
  309. It also allows you to view the exit code of the program, and the
  310. elapsed time of the program, by supplying the appropriate options on
  311. the command line.
  312.  
  313. Note that `redir' is built with command-line expansion and response
  314. files disabled, so as to allow the application to control that
  315. themselves.  This means that you can't use those features to provide
  316. `redir''s options or the command name, but if you use them for the
  317. command's options, the command will do the expansion if it wants to.
  318.  
  319. The exit code of `redir' is 1 if it exits on its own accord, else it
  320. returns the same error code as the program it runs.
  321.  
  322. Usage: `redir' [`-i' FILE] [`-o' FILE] [`-oa' FILE] [`-e' FILE] [`-ea'
  323. FILE] [`-eo'] [`-oe'] [`-x'] [`-t'] COMMAND [ARGS . . .]
  324.  
  325. `-i FILE'
  326.      Redirect stdandard input from file
  327.  
  328. `-o FILE'
  329.      Redirect standard output to file
  330.  
  331. `-oa FILE'
  332.      Append standard output to file
  333.  
  334. `-e FILE'
  335.      Redirect standard error to file
  336.  
  337. `-ea FILE'
  338.      Append standard error to file
  339.  
  340. `-eo'
  341.      Redirect standard error to standard output
  342.  
  343. `-oe'
  344.      Redirect standard output to standard error
  345.  
  346. `-x'
  347.      Print the exit code of the command after it exits.  If the exit
  348.      code is 0..255, it is printed as is.  If it is not, the low byte
  349.      (0..255) is printed in decimal and the whole value is also printed
  350.      in hex.
  351.  
  352. `-t'
  353.      Print elapsed time, either in seconds (for short runs) or
  354.      hours:minutes:seconds.
  355.  
  356. Options are processed in the order they are encountered.  Thus, "-o foo
  357. -eo" means "redirect output to foo, then redirect errors there also",
  358. whereas "-eo -o foo" means "send errors to where output was going, then
  359. move output to foo".
  360.  
  361. Examples:
  362.  
  363. To redirect errors to a file:
  364.  
  365.      redir -e errors.lst command ...
  366.  
  367. To redirect output to a file, and errors through a pipe:
  368.  
  369.      redir -eo -o prog.out command ... | pipe
  370.  
  371. 
  372. File: utils.info,  Node: djsplit,  Next: djmerge,  Prev: redir,  Up: Top
  373.  
  374. djsplit
  375. *******
  376.  
  377. The `djsplit' and `djmerge' programs are designed to assist in
  378. transporting files across unreliable channels or small media (like
  379. floppies).  `djsplit' takes a big file and splits it into up to 1000
  380. smaller files.  `djmerge' puts them back together again.
  381.  
  382. Usage: `djsplit' INPUTFILE CHUNKSIZE OUTPUTBASE
  383.  
  384. Each output file is made from appending a sequence number to
  385. OUTPUTBASE.  For example:
  386.  
  387.      djsplit foo.tgz 1300k footgz
  388.  
  389. would result in `footgz.000', `footgz.001', etc.
  390.  
  391. The `chunksize' parameter can be expressed as bytes (NNN),
  392. kilobytes(NNNk) or megabytes (NNNm).  The number NNN *must* be an
  393. integer; for example, `1.1m' will *not* work.
  394.  
  395. 
  396. File: utils.info,  Node: djmerge,  Next: texi2ps,  Prev: djsplit,  Up: Top
  397.  
  398. djmerge
  399. *******
  400.  
  401. The `djsplit' and `djmerge' programs are designed to assist in
  402. transporting files across unreliable channels or small media (like
  403. floppies).  `djsplit' takes a big file and splits it into up to 1000
  404. smaller files.  `djmerge' puts them back together again.
  405.  
  406. Usage: `djmerge' INPUTBASE OUTPUTFILE
  407.  
  408. Each input file is made from appending a sequence number to INPUTBASE.
  409. For example, given `footgz.000', `footgz.001', etc,
  410.  
  411.      djmerge footgz foo.tgz
  412.  
  413. would result in `foo.tgz' being created.
  414.  
  415. 
  416. File: utils.info,  Node: texi2ps,  Next: update,  Prev: djmerge,  Up: Top
  417.  
  418. texi2ps
  419. *******
  420.  
  421. `texi2ps' is a modified version of `makeinfo' that quickly turns
  422. texinfo files (such as info files are generated from) into crude
  423. Postscript files, ready for printing.  The program is designed to
  424. produce a crude page, so please don't complain if the printed copy looks
  425. ugly.  If you want clean pages, get and install TeX and print it with
  426. that.  It will produce a much cleaner print.  I'm also pretty sure that
  427. texi2ps won't support 100% of the texinfo documents out there.  Again,
  428. if you want it right use TeX.
  429.  
  430. Note that the input files are texinfo files, not TeX or LaTeX or info
  431. files.  In normal djgpp distributions, the texinfo files are part of
  432. the source distributions, and the info files are in the binary
  433. distributions.
  434.  
  435. The default settings produce a pretty densely packed page - small font,
  436. small margins.  You can set the margins and font even smaller to save on
  437. paper, or make them bigger for more conventional manuals.
  438.  
  439. Usage: `texi2ps' [`-f' SIZE] [`-I' DIR] [`-I'DIR] [`-v'] [`-m' PTS] FILE
  440.  
  441. `-f SIZE'
  442.      The font size, in points.  The default is 10 points.
  443.  
  444. `-I PATH'
  445.      Specifies an additional path to search for include files.
  446.  
  447. `-v'
  448.      Print verbose messages about files read, nodes encountered, and
  449.      pages generated.
  450.  
  451. `-m PTS'
  452.      Set the margin size in points.  The default is 54 points, or 3/4
  453.      inches (72 points = 1 inch).
  454.  
  455. Note that the Postscript file is sent to standard output, so you must
  456. redirect the output to a file or a printer.
  457.  
  458. 
  459. File: utils.info,  Node: update,  Prev: texi2ps,  Up: Top
  460.  
  461. update
  462. ******
  463.  
  464. `update' is a fancy copy-if-needed program.  Basically, it compares the
  465. two files you give it, and if they differ, copies one to the other.
  466. This is useful in makefiles where a file is generated often, but its
  467. contents changes rarely, and other files depend on it.  For example,
  468. `bison' emits a header file each time it parses the grammar.  The
  469. header rarely changes, but the grammar changes often.  So, you use
  470. `update' to copy the header to its real name only when it changes, and
  471. everything else won't need to be recompiled each time.
  472.  
  473. Usage: `update' NEW_FILE COPIED_TO
  474.  
  475. Example:
  476.  
  477.      foo.c foo.h : foo.y
  478.              bison foo.y
  479.              update y_tab.h foo.h
  480.              update y_tab.c foo.c
  481.  
  482.  
  483. 
  484. Tag Table:
  485. Node: Top207
  486. Node: bin2h990
  487. Node: djecho1353
  488. Node: djtar2089
  489. Node: dtou10622
  490. Node: utod10894
  491. Node: gxx11164
  492. Node: redir11436
  493. Node: djsplit13948
  494. Node: djmerge14692
  495. Node: texi2ps15278
  496. Node: update16850
  497. 
  498. End Tag Table
  499.